---
type: integration
title: '@astrojs/svelte'
description: 了解如何使用 @astrojs/svelte 框架来拓展 Astro 项目中的组件支持
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/svelte/'
category: renderer
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Since from '~/components/Since.astro';

此 **[Astro 集成][astro-integration]** 为你的 [Svelte](https://svelte.dev/) 组件启用服务器端渲染和客户端注入。它支持 Svelte 3、Svelte 4 以及 Svelte 5 版本（实验性）。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为[手动安装集成](#手动安装)。

安装 `@astrojs/svelte`，需要在你的项目工程中依次运行以下命令：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add svelte
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add svelte
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add svelte
  ```
  </Fragment>
</PackageManagerTabs>

如果你有任何问题，[欢迎随时在 GitHub 上开个 issue 来向我们报告](https://github.com/withastro/astro/issues) 然后尝试执行以下的手动安装步骤。

### 手动安装

首先，安装 `@astrojs/svelte` 包:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/svelte
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/svelte
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/svelte
  ```
  </Fragment>
</PackageManagerTabs>

大多数包管理器也会安装相关的对等依赖项。如果在启动 Astro 时看到 "Cannot find package 'svelte'" (或类似的)警告，则需要安装 Svelte：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install svelte
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add svelte
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add svelte
  ```
  </Fragment>
</PackageManagerTabs>

然后，使用 `integrations` 属性将集成应用到你的 `astro.config.*` 文件中：

```js title="astro.config.mjs" ins={2} ins="svelte()"
import { defineConfig } from 'astro/config';
import svelte from '@astrojs/svelte';
export default defineConfig({
  // ...
  integrations: [svelte()],
});
```

## 入门

要在 Astro 使用你的 Svelte 组件，你可以移步我们的 [UI 框架文档][astro-ui-frameworks]. 你将会了解到：

* 📦 如何加载框架组件
* 💧 客户端合成注水选项
* 🤝 将框架混合和嵌套在一起的时机

## 选项


此集成由 `@sveltejs/vite-plugin-svelte` 提供支持的，要定制 Svelte 编译器，你可以传递选项给当前集成，查看 [`@sveltejs/vite-plugin-svelte`文档](https://github.com/sveltejs/vite-plugin-svelte/blob/HEAD/docs/config.md) 获取更多细节。

### 默认选项

此集成将以下默认选项传递给 Svelte 编译器：

```js
const defaultOptions = {
  emitCss: true,
  compilerOptions: { dev: isDev, hydratable: true },
  preprocess: vitePreprocess(),
};
```

这些 `emitCss`、 `compilerOptions.dev` 和 `compilerOptions.hydratable` 选项对于构建过程来说是必传的，并且不能被赋值。

如果你传递自定义的 `preprocess` 选项，这**将会**覆盖 [`vitePreprocess()`](https://github.com/sveltejs/vite-plugin-svelte/blob/HEAD/docs/preprocess.md) 的默认值。确保根据你的项目实际需求来开启预处理配置。

你可以通过在 `astro.config.mjs` 或者 `svelte.config.js` 文件中传递这个选项配置给 `svelte` 集成，这两种方式都将覆盖默认的 `preprocess` 设置：

```js title="astro.config.mjs" "preprocess: []"
import { defineConfig } from 'astro/config';
import svelte from '@astrojs/svelte';

export default defineConfig({
  integrations: [svelte({ preprocess: [] })],
});
```

```js title="svelte.config.js"
// svelte.config.js
export default {
  preprocess: [],
};
```

## TypeScript 智能提示

<Since v="2.0.0" pkg="@astrojs/svelte" />

如果你的文件中使用了像 TypeScript 或 SCSS 预处理器，你可以创建一个 `svelte.config.js` 文件，确保 Svelte IDE 拓展能够正确解析 Svelte 文件。

```js title="svelte.config.js"
import { vitePreprocess } from '@astrojs/svelte';

export default {
  preprocess: vitePreprocess(),
};
```

当你运行 `astro add svelte` 指令的时候，将自动为你添加配置文件。

[astro-integration]: /zh-cn/guides/integrations-guide/

[astro-ui-frameworks]: /zh-cn/guides/framework-components/#使用框架组件
